Sleeper API MCP

# .cursorrules (v5) ruleType: always ### 1. Target Directory Layout & Cursor Integration * Work in an existing folder named `mcp_<feature>` (e.g. `mcp_pbp_data`). * Cursor will invoke **stdio servers** via a shell command; do **not** nest further directories. * For **project‑specific** config, users define `.cursor/mcp.json`; for **global** usage, `~/.cursor/mcp.json`. ### 2. File Scaffold * `mcp.json` — metadata: * `name`: matches folder name without `mcp_`. * `version`, `description`, `transports`, `tools`, `schemas`. * `server.py` / `server.ts` — protocol wiring + tool implementations. * `README.md` — usage, **ENV var names only** (`export VAR=…`), example `.cursor/mcp.json` snippet, further reading link. * Optional `tests/` — unit tests and a smoke test entrypoint. ### 3. Environment‑Only Secrets & Cursor Config * **Never** include real API keys/placeholders in code or docs. * Document only variable names (e.g. `export MYAPP_API_KEY=…`). * Cursor’s `.cursor/mcp.json` can inject env: ```json { "mcpServers": { "my-server": { "command": "python server.py", "env": { "MYAPP_API_KEY": "$MYAPP_API_KEY" } } } } ``` * In code, use `os.getenv("MYAPP_API_KEY")` or `process.env.MYAPP_API_KEY`; fail fast if missing. ### 4. Protocol & Transport Compliance #### 4.1 JSON‑RPC Envelope * Must wrap all messages in JSON-RPC 2.0: `{ jsonrpc:"2.0", id?, method, params? }`. * **Requests/Responses** carry `id`; **Notifications** **must** omit `id`. * On unknown methods or invalid params, return structured JSON-RPC error (`code`, `message`, `data`). #### 4.2 Supported Transports * **stdio** (Cursor default): * Cursor auto‑runs the `command` from `.cursor/mcp.json` (shell command). * Declare `"stdio"` in `mcp.json` under `"transports"`. * **SSE** (opt‑in): * Cursor uses provided URL (e.g. `http://host:port/sse`). * Declare `"sse"` in `mcp.json`. * Enforce TLS, localhost binding, `Origin` header validation, auth on `/sse` & `/messages`. * **Custom**: * List custom names in `mcp.json`. * Implement the MCP `Transport` interface. #### 4.3 Transport Logging & Limits * `DEBUG` logs: `start()`, envelopes in/out, `close()`. * `INFO` logs: connection established, disconnected. * Never log secrets. * Cursor currently loads only the first **40 tools**; keep tool count concise. ### 5. Separation of Concerns * No embedded agent prompts or orchestration in MCPs—all in super‑agent. * Each MCP focuses on one domain (e.g. `fetch_odds`, `scrape_reddit`, `push_to_db`). * Business logic in helper functions; `server.*` only handles protocol wiring. ### 6. Idempotence & Logging * Data‐write tools must support idempotent upserts. * Structured logging: `INFO` for operations, `DEBUG` for payloads. * Avoid logging raw inputs with secrets. ### 7. Type Safety & Documentation * Use type hints/TS interfaces for all I/O. * Keep docstrings and `mcp.json` schemas in sync. ### 8. Resources (Cursor Notes) * Cursor **does not** support MCP Resources yet—focus on Tools only. * If planning resource endpoints, document them in `README.md` for future support. ### 9. Testing & Examples * `tests/` must include: * Unit test per tool (mock external calls). * Smoke test: call `listTools()` and invoke each tool. * In `README.md`, add `.cursor/mcp.json` snippet and: ```bash # stdio example cursor run-mcp my-server ``` ### 10. Multi‑MCP GitHub Strategy * Root `workspace.json` lists all `mcp_<feature>` dirs for Cursor. * CI: for each dir, `cursor run-tests` or `pytest`/`npm test`. * Tag repo `vX.Y.Z`; bump each `mcp.json` version per change. ### 11. Further Reading * MCP core & transports: [https://modelcontextprotocol.io/docs/concepts/transports](https://modelcontextprotocol.io/docs/concepts/transports) * MCP with LLMs: [https://modelcontextprotocol.io/llms-full.txt](https://modelcontextprotocol.io/llms-full.txt) ### Final Checklist * [ ] Scaffold ran inside existing `mcp_<feature>` dir. * [ ] No API keys in code/docs; only ENV\_VAR names. * [ ] Secrets loaded via `os.getenv()`/`process.env`. * [ ] JSON‑RPC envelopes validated; errors per spec. * [ ] Transports declared in `mcp.json` match code. * [ ] Tool count ≤40 or critical tools prioritized. * [ ] Tests pass in CI for all MCPs.